<html>
	<head>
		<style type="text/css">
			/* <![CDATA[ */
			@import "http://www.tigris.org/branding/css/tigris.css";
			@import "http://www.tigris.org/branding/css/inst.css";
			/*  ]]> */
		</style>
		<link rel="stylesheet" type="text/css" href="http://www.tigris.org/branding/css/print.css" media="print" />
		<script src="http://www.tigris.org/branding/scripts/tigris.js" type="text/javascript"/>
		<title>Atlas Project Documentation - Profiles</title>
	</head>

	<body>
		<div class="h2 app" style="border-left: 0px" id="customcontent">
			<h2>Defining an Application's Applistructure</h2>
			<p>
				An Application's applistructure consists of a Framework and a number of Implementation Elements, as defined by one or more Profiles.
				Each Implementation Element is the output of a template
				of functionality.  These templates often extend functionality from within a Framework or a Framework Plugin.  To arrive at Implementation
				Elements, a Profile specifies one or more Targets.  Each Target uses a Generator, which is fed Metadata about your application's key
				abstractions to generate Implementation Elements.  These elements are source code that combine with your Framework to account for
				the bulk of an Application's code base.  This following diagram visually depicts elements that make up an Application.  In the next
				section, we will walk through a concrete example of an application's applistructure definition.
			</p>
			<p>
				<img src="../images/codegenmodel.jpg" alt="UML diagram of the components that define an application"></img>
				<div>UML Representation of a the Atlas code generation model</div>
			</p>

			<h2>Example: The Anatomy of a Simple Application's Applistructure</h2>
			<p>
				Before getting into the details of our application, we need to create a specification that Atlas can use to create our applistructure.  Atlas
				does this by specifying a project that defines the application's MDA settings, typically with the naming convetion of &lt;application name&gt;-mda.
				These projects are defined using <a href="http://maven.apache.org">Maven</a> (see Maven's site for more information
				on its use and configuration). This <a href="http://atlas.tigris.org/source/browse/atlas/trunk/atlas-examples/atlas-examples-mda/">example</a>
				is available for download and can be used as a pattern.
			</p>

			<h3>Select a Framework</h3>
			<p>
				When creating a new application, the first consideration is to base it on a Framework.
				<a href="http://atlas.tigris.org/source/browse/atlas/trunk/atlas-java">Atlas-java</a> is a Framework that supplied by Atlas and will
				be used in this example.  A Framework provides the static applistructure for the Application.  Unlike many other frameworks, Atlas's MDA
				pattern	allows generic funcitonality to be encapsulated into a Framework which can then be augmented by generated Implementation Elements.
				These generated Implementation Element represent on-demand applistructure.  The	result is an application that has the feel and benefits of
				a hand-coded effort with the productivity and quality of a more generic	approach.  In the case of a atlas-java, the Framework defines base
				interfaces, abstract implementations and scaffolding code for a Java applistructure.  Meanwhile, atlas-java-mda provides strongly-typed
				on-demand applistructure.  Framework Plugins fortify this applistructure via the same mechanisms by adding loosly-coupled implementations
				that can leverage third-party components.  We'll assemble all these pieces together in the following section on profiles.
			</p>

			<h3>Assembling the Application's Applistructure Profile</h3>
			<p>
				Now that a Framework has been choosen, we need to configure the applistructure to generate its Implementation Elements.  This will be done
				by specifying the Profile of the application in the our &lt;application name&gt;-mda project, which is atlas-examples-mda in this case.
				Profiles are specified in a profiles.xml file.  Each Profile consists of zero or more Target references and can extend or include other
				Profiles.  In this example, we'll extend the base atlas-java profile,
				<a href="http://atlas.tigris.org/source/browse/atlas/trunk/atlas-java-mda/src/main/resources/profiles.xml">java-base</a>.  Additionally,
				POJO service implementation targets will specified to implement the atlas-java Framework's service interfaces.  Profile includes of
				<a href="http://atlas.tigris.org/source/browse/atlas/trunk/atlas-hibernate-mda/src/main/resources/profiles.xml">java-hibernate</a>,
				<a href="http://atlas.tigris.org/source/browse/atlas/trunk/atlas-spring-mda/src/main/resources/profiles.xml">java-core-spring</a> and
				<a href="http://atlas.tigris.org/source/browse/atlas/trunk/atlas-struts-mda/src/main/resources/profiles.xml">java-struts-forms</a>
				will defined to implement atlas-java's DAO, factory and form interfaces, respectively. This profile will be called
				<a href="http://atlas.tigris.org/source/browse/atlas/trunk/atlas-examples/atlas-examples-mda/src/main/resources/profiles.xml">example-simple-implementation</a>.
				This profile leverages all three profile specification mechanisms.
			</p>
			<p>
				A Profile can reference any other Profile on the classpath.  You will notice that each of the Profiles referenced in
				example-simple-implementation originates in a different &lt;application name&gt;-mda project.  Targets follow the same pattern.  The pair of
				Targets referenced in our example Profile also originate in a different &lt;application name&gt;-mda project.  The atlas-java-mda project
				represents a Framework that defines both Profiles and Targets.  The atlas-hibernate-mda, atlas-spring-mda and atlas-struts-mda projects
				represent Framework Plugins.  That is, these projects represent third party components that can be generated into an Application to meet
				the needs of a Framework.  Each of these Framework Plugins also can have a runtime component, atlas-hibernate, atlas-spring and atlas-struts,
				that defines any base functionality that is needed by the Framework Plugin at runtime.  In most cases, the generated Implementation Elements
				derive from source elements in the runtime project of their associated Framework Plugin.  For instance, the Hibernate Framework Plugin
				specifies an abstract
				<a href="http://atlas.tigris.org/source/browse/atlas/trunk/atlas-hibernate/src/main/java/org/tigris/atlas/persist/hibernate/DaoImpl.java">DAO implementnation</a>
				that implements atlas-java Framework's
				<a href="http://atlas.tigris.org/source/browse/atlas/trunk/atlas-java/src/main/java/org/tigris/atlas/persist/Dao.java">DAO interface</a>.
				By wiring up our Profile to use atlas-hibernate-mda's java-hibernate profile, concrete subclasses will be generated that extend the abstract
				DAO implementation in atlas-hibernate.  The following section will walk through how Implementation Elements are generated and will continue
				with our concrete example by delving into the the concrete DAO classes generated for use with Hibernate.
			</p>

			<h3>How Targets Relate to Implementation Elements</h3>
			<p>
				A Target can be referenced by one or more Profiles to generate Implementation Elements.  In order to faciltitate this relationship between
				Profiles and Targets, the later is defined in its own file. Applications will not typically need to specify their own Targets, but they
				can should the need arise.  Frameworks and Framework Plugins will typically	define Targets. Each Target specifies a template and a Generator.  When a
				Profile is read by Atlas, each Target is loaded and a Generator is executed.  The Generator is passed the template to use, the name of
				the output file that should be generated and an indicator as to whether or not the output should be overwritten if it already exists.  A
				Generator typically merges Metadata against the passed template, resulting in the Implementation Element(s) being written to the defined
				location.
			</p>
			<p>
				In the case of our DAO example, both
				<a href="http://atlas.tigris.org/source/browse/atlas/trunk/atlas-java-mda/src/main/resources/targets.xml">atlas-java-mda Framework Targets</a>
				and
				<a href="http://atlas.tigris.org/source/browse/atlas/trunk/atlas-hibernate-mda/src/main/resources/targets.xml">atlas-hiberate-mda Framework Targets</a>
				exist.  In atlas-java-mda, a the Target dataAccessObjects specifies that generation of DAO interfaces via the
				<a href="http://atlas.tigris.org/source/browse/atlas/trunk/atlas-java-mda/src/main/resources/templates/dao.java.vm">dao.java.vm</a>
				template.  This Target uses a Generator that iterates over each Entity Metadata element and produces an Implementation Element for each Entity.
				(the DAO Java interface files, in this case) The Target in atlas-hibernate-mda,
				<a href="http://atlas.tigris.org/source/browse/atlas/trunk/atlas-hibernate-mda/src/main/resources/templates/dao.hibernate.java.vm">dataAccessObjectHibernateImpls</a>,
				uses the same kind of Generator to produce a Hibernate DAO Implementation file (DAO Java class files, in this case) that extends the
				base Hibernate DAO in the atlas-hibernate Framework Plugin project.  This same concept is used with the remaining Metadata types to produce
				Service, Enumerations and Forms.  It is important to realize that each different kind of Implementation Element needs its own Target.
			</p>
			<p>
				All templates in Atlas are written in
				<a href="http://jakarta.apache.org/velocity">Apache's Velocity</a> templating language (see Velocity's site for more information
				on its use and configuration).
			</p>

		</div>
	</body>
</html>
